---
title: Google
icon: Chrome
---

import { ZoomableImage } from "@/components/ui/zoomable-image";

Google is one of Palmr's officially supported OIDC providers, offering secure and reliable authentication through Google OAuth 2.0. This integration allows users to sign in to Palmr using their existing Google accounts, providing a seamless single sign-on experience.

<ZoomableImage src="/assets/v3/oidc/google/sign-in-with-google.png" alt="Sign in with Google" />

## Why use Google authentication?

Google authentication provides several advantages for both administrators and users:

- **Seamless login experience** - Users can access Palmr with their existing Google accounts
- **Enhanced security** - Leverage Google's robust security infrastructure and two-factor authentication
- **Reduced password fatigue** - No need to create and remember additional passwords
- **Enterprise integration** - Perfect for organizations already using Google Workspace
- **Automatic user provisioning** - New users are created automatically upon first login

---

## Prerequisites

Before configuring Google authentication, ensure you have:

- **Google Cloud Console access** - Ability to create and manage projects
- **Admin privileges in Palmr** - Required to configure OIDC settings
- **Domain ownership** - For production deployments with custom domains

> **Note:** Google is pre-configured as an official provider in Palmr, which means the technical configuration is handled automatically. You only need to provide your OAuth credentials.

---

## Setting up Google Cloud Console

### Creating a Google Cloud project

To get started with Google authentication, you'll need to set up a project in Google Cloud Console.

1. **Navigate to Google Cloud Console**: Go to [console.cloud.google.com](https://console.cloud.google.com/)

<ZoomableImage src="/assets/v3/oidc/google/cloud-console-home.png" alt="Google Cloud Console Home" />

2. **Create or select a project**: Choose an existing project or create a new one for your Palmr installation

<ZoomableImage src="/assets/v3/oidc/google/select-project-modal.png" alt="Google Cloud Console Select Project Modal" />

3. **Enable the project**: Ensure the project is active and selected

### Configuring OAuth consent screen

The OAuth consent screen is what users see when they authenticate with Google.

1. **Access OAuth consent screen**: Navigate to **APIs & Services** > **OAuth consent screen**

<ZoomableImage
  src="/assets/v3/oidc/google/oauth-consent-dropdown.png"
  alt="Google Cloud Console OAuth Consent Dropdown"
/>

2. **Choose user type**:
   - **Internal** - For Google Workspace organizations (users within your domain only)
   - **External** - For public use (any Google user can authenticate)

<ZoomableImage src="/assets/v3/oidc/google/user-type-select.png" alt="Google Cloud Console User Type Select" />

3. **Fill required information**:
   - **Application name**: Enter a descriptive name like "Palmr File Sharing"
   - **User support email**: Provide a valid support email address
   - **Developer contact information**: Add your contact email for Google communications

> **Tip:** For business use, choose "Internal" if you have Google Workspace. This restricts access to your organization's users and simplifies the approval process.

### Creating OAuth 2.0 credentials

Now you'll create the actual credentials that Palmr will use to authenticate with Google.

1. **Navigate to Credentials**: Go to **APIs & Services** > **Credentials**

<ZoomableImage src="/assets/v3/oidc/google/credentials-select.png" alt="Google Cloud Console Credentials select" />

2. **Create OAuth client**: Click **+ CREATE CREDENTIALS** > **OAuth client ID**

<ZoomableImage
  src="/assets/v3/oidc/google/create-oauth-client-id.png"
  alt="Google Cloud Console Create OAuth Client ID"
/>

3. **Select application type**: Choose **Web application**

<ZoomableImage src="/assets/v3/oidc/google/web-app-select.png" alt="Google Cloud Console Web App Select" />

4. **Configure authorized URIs and authorized redirect URIs**:

You'll need to configure several URLs in your Google Cloud Console credentials. Here's what to add for each environment:

### Authorized URIs

| Environment | URL                           |
| ----------- | ----------------------------- |
| Production  | `https://yourdomain.com`      |
| Development | `http://localhost:3000`       |
| Custom Port | `https://yourdomain.com:5487` |

### Authorized Redirect URIs

| Environment | URL                                                              |
| ----------- | ---------------------------------------------------------------- |
| Production  | `https://yourdomain.com/api/auth/providers/google/callback`      |
| Development | `http://localhost:3000/api/auth/providers/google/callback`       |
| Custom Port | `https://yourdomain.com:5487/api/auth/providers/google/callback` |

> **Note:** Replace `yourdomain.com` with your actual domain name in all production and custom port URLs.
> **Note:** You can add multiple redirect URIs for different environments (development, staging, production).

<ZoomableImage src="/assets/v3/oidc/google/allowed-urls.png" alt="Google Cloud Console Allowed URLs" />

5. **Create and save credentials**: Click **Create** and copy both the **Client ID** and **Client Secret**

<ZoomableImage
  src="/assets/v3/oidc/google/oauth-client-created.png"
  alt="Google Cloud Console Client ID and Client Secret"
  legend="The client ID and client secret shown in the image are examples only (fake credentials). You must use your own credentials from Google Cloud Console."
/>

> **Important:** Replace `yourdomain.com` with your actual domain. You can add multiple URIs for different environments (development, staging, production).

---

## Configuring Palmr

### Accessing OIDC settings

To configure Google authentication in Palmr, you need administrator access to the settings panel.

1. **Login as administrator**: Sign in to Palmr with an admin account

2. **Access settings**: Click your profile picture in the header and select **Settings**

3. **Navigate to authentication**: Find and click on the **Authentication Providers** configuration section

<ZoomableImage src="/assets/v3/oidc/auth-providers.png" alt="Palmr Authentication Providers" />

### Enabling Google provider

Google comes pre-configured as an official provider, so the setup process is streamlined.

1. **Locate Google provider**: Find Google in the list of available providers

2. **Enable the provider**: Toggle the status to **Enabled**

<ZoomableImage src="/assets/v3/oidc/google/palmr-enabled-google.png" alt="Palmr Authentication Providers" />

After enabling the provider, click on the pen icon to configure the provider.

3. **Configure credentials**:
   - **Client ID**: Paste the Client ID from Google Cloud Console
   - **Client Secret**: Paste the Client Secret from Google Cloud Console
   - **Scopes**: Add the scopes you want to use. The default scopes are `openid`, `profile`, and `email`.

<ZoomableImage src="/assets/v3/oidc/google/edit-google.png" alt="Edit Google Provider" />

### Advanced configuration options

Configure additional settings to customize the authentication behavior:

**Auto Registration**: Enable this to automatically create user accounts when someone authenticates for the first time.

**Admin Email Domains**: Specify domains that should automatically receive admin privileges. For example, entering `yourcompany.com` will grant admin access to anyone with an email from that domain.

**Sort Order**: Control where the Google login button appears relative to other authentication providers.

**Icon**: you can choose the icon you want to use for the Google login button (default is `FcGoogle`).

<ZoomableImage src="/assets/v3/oidc/google/google-icon.png" alt="Google Icon" />

> **Security consideration:** Be cautious with auto-registration and admin domains. Only enable these if you trust the user base or have domain restrictions in place.

---

## Account linking

By default, if a user is already registered in Palmr with their Google email, they will be automatically linked to their Palmr account.

> **Note:** You can't disable account linking. If you want to unlink a user from their Google account, you need to delete the user from Palmr.

---

## Technical configuration

Google's technical configuration is handled automatically, but understanding the setup can help with troubleshooting:

```yaml
Provider Type: OAuth 2.0 with OIDC Discovery
Issuer URL: https://accounts.google.com
Authorization Endpoint: /o/oauth2/v2/auth
Token Endpoint: /o/oauth2/token
UserInfo Endpoint: https://www.googleapis.com/oauth2/v3/userinfo
Scopes: openid profile email
```

### Field mappings

Palmr automatically maps Google user information to local user accounts:

- **User ID**: Maps from Google's `sub` field
- **Email**: Maps from Google's `email` field
- **Full Name**: Maps from Google's `name` field
- **First Name**: Maps from Google's `given_name` field
- **Last Name**: Maps from Google's `family_name` field
- **Avatar**: Maps from Google's `picture` field

---

## Testing the configuration

### Verifying the setup

After configuring Google authentication, test the integration to ensure everything works correctly.

1. **Check login page**: Navigate to your Palmr login page and verify the "Sign in with Google" button appears

2. **Test authentication flow**: Click the Google sign-in button and complete the authentication process

3. **Verify user creation**: Confirm that a new user account is created (if auto-registration is enabled)

### Login flow verification

The complete authentication process should work as follows:

1. **User clicks "Sign in with Google"**: The browser redirects to Google's authentication page
2. **User authenticates with Google**: User enters their Google credentials or confirms existing session
3. **Google redirects back to Palmr**: User returns to Palmr with authentication tokens
4. **Palmr creates or updates user**: User account is automatically managed based on your configuration
5. **User accesses Palmr**: User is logged in and can use all features according to their permissions

---

## Troubleshooting common issues

### Redirect URI mismatch error

**Error message**: `Error 400: redirect_uri_mismatch`

**Cause**: The redirect URI in your request doesn't match what's configured in Google Cloud Console.

**Solution**:

1. Check the exact URL in the error message
2. Add this exact URL to your Google Cloud Console credentials
3. Ensure you include the correct protocol (http/https) and port
4. Remove any trailing slashes unless they're in the error message

### Access denied error

**Error message**: `Error 403: access_denied`

**Cause**: User denied permissions or the OAuth consent screen isn't properly configured.

**Solution**:

1. Verify the OAuth consent screen is published (for External user type)
2. Check that required scopes are correctly configured
3. For Internal applications, ensure the user belongs to your Google Workspace organization
4. Review and simplify the permissions you're requesting

### Invalid client error

**Error message**: `Error 401: invalid_client`

**Cause**: Incorrect Client ID or Client Secret.

**Solution**:

1. Double-check that you've copied the credentials correctly from Google Cloud Console
2. Ensure there are no extra spaces or characters in the credentials
3. Regenerate credentials if necessary
4. Verify you're using the correct project in Google Cloud Console

### Discovery endpoint issues

**Cause**: Network connectivity problems or DNS resolution issues.

**Solution**:

1. Check server firewall and network connectivity
2. Verify DNS resolution from your server
3. Consider proxy or CDN configurations that might block the request

---

## Security best practices

### Credential management

- **Never expose secrets**: Keep your Client Secret secure and never commit it to version control
- **Rotate credentials regularly**: Generate new credentials periodically for enhanced security
- **Use environment variables**: Store sensitive configuration in environment variables, not config files
- **Monitor access logs**: Regularly review authentication logs for suspicious activity

### Domain and user restrictions

- **Limit admin domains**: Only add trusted domains to the admin list
- **Review auto-registration**: Consider disabling auto-registration if you need manual user approval
- **Use Internal OAuth**: For organizations with Google Workspace, use Internal OAuth consent screen
- **Regular access reviews**: Periodically review user access and remove inactive accounts

### Production considerations

- **Use HTTPS**: Always use HTTPS in production environments
- **Configure proper domains**: Use production domains in Google Cloud Console
- **Test thoroughly**: Verify the complete authentication flow before going live
- **Plan for failures**: Have fallback authentication methods available

---

## Next steps

With Google authentication configured, you might want to:

- **Configure additional providers**: Set up other OIDC providers for more authentication options
- **Customize user management**: Fine-tune auto-registration and admin assignment rules
- **Review security settings**: Ensure your authentication setup meets your security requirements
- **Monitor usage**: Keep track of authentication patterns and user activity

For more information about OIDC authentication in Palmr, see the [OIDC Authentication overview](/docs/v3-beta/oidc-authentication).

## Useful resources

- [Google Identity Platform Documentation](https://developers.google.com/identity)
- [OAuth 2.0 for Web Server Applications](https://developers.google.com/identity/protocols/oauth2/web-server)
- [OpenID Connect](https://developers.google.com/identity/protocols/oauth2/openid-connect)
- [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
